</refsect2>
- <refsect2>
- <title>Key bindings</title>
-
- <para>
- In order to extend key bindings affecting different widgets,
- GTK supports the @binding-set rule to parse a set of bind/unbind
- directives. Note that in order to take effect, the binding sets
- defined in this way must be associated with rule sets by setting
- the -gtk-key-bindings property.
- </para>
-
- <para>
- The syntax for @binding-set rules is as follows:
- </para>
-
-<literallayout><code>〈binding set rule〉 = @binding-set 〈binding name〉 { [ [ 〈binding〉 | 〈unbinding〉 ] ; ]* }</code>
-<code>〈binding〉 = bind "〈accelerator〉" { 〈signal emission〉* }</code>
-<code>〈signal emission〉 = "〈signal name〉" ( [ 〈argument〉 [ , 〈argument〉 ]* ]? }</code>
-<code>〈unbinding〉 = unbind "〈accelerator〉"</code>
-</literallayout>
-
- <para>
- where 〈accelerator〉 is a string that can be parsed by gtk_accelerator_parse(),
- 〈signal name〉 is the name of a keybinding signal of the widget in question,
- and the 〈argument〉 list must be according to the signals declaration.
- </para>
-
- <example>
- <title>An example for using the @binding-set rule</title>
- <programlisting><![CDATA[
-@binding-set binding-set1 {
- bind "<alt>Left" { "move-cursor" (visual-positions, -3, 0) };
- unbind "End";
-};
-
-@binding-set binding-set2 {
- bind "<alt>Right" { "move-cursor" (visual-positions, 3, 0) };
- bind "<alt>KP_space" { "delete-from-cursor" (whitespace, 1)
- "insert-at-cursor" (" ") };
-};
-
-entry {
- -gtk-key-bindings: binding-set1, binding-set2;
-}
-]]></programlisting>
- </example>
-
- </refsect2>
-
</refsect1>
</refentry>
* must both be true. For example, by calling gtk_widget_set_can_focus()
* in the widget’s initialisation function; and by calling
* gtk_widget_grab_focus() when the widget is clicked.
- *
- * # Installing a key binding
- *
- * A CSS file binding consists of a “binding-set” definition and a match
- * statement to apply the binding set to specific widget types. Details
- * on the matching mechanism are described under
- * [Selectors][gtkcssprovider-selectors]
- * in the #GtkCssProvider documentation. Inside the binding set
- * definition, key combinations are bound to one or more specific
- * signal emissions on the target widget. Key combinations are strings
- * consisting of an optional #GdkModifierType name and
- * [key names][gdk3-Keyboard-Handling]
- * such as those defined in `gdk/gdkkeysyms.h`
- * or returned from gdk_keyval_name(), they have to be parsable by
- * gtk_accelerator_parse(). Specifications of signal emissions consist
- * of a string identifying the signal name, and a list of signal specific
- * arguments in parenthesis.
- *
- * For example for binding Control and the left or right cursor keys
- * of a #GtkEntry widget to the #GtkEntry::move-cursor signal (so
- * movement occurs in 3-character steps), the following binding can be
- * used:
- *
- * |[ <!-- language="CSS" -->
- * @binding-set MoveCursor3
- * {
- * bind "<Control>Right" { "move-cursor" (visual-positions, 3, 0) };
- * bind "<Control>Left" { "move-cursor" (visual-positions, -3, 0) };
- * }
- *
- * entry
- * {
- * -gtk-key-bindings: MoveCursor3;
- * }
- * ]|
- *
- * # Unbinding existing key bindings
- *
- * GTK+ already defines a number of useful bindings for the widgets
- * it provides. Because custom bindings set up in CSS files take
- * precedence over the default bindings shipped with GTK+, overriding
- * existing bindings as demonstrated in
- * [Installing a key binding][gtk-bindings-install]
- * works as expected. The same mechanism can not be used to “unbind”
- * existing bindings, however.
- *
- * |[ <!-- language="CSS" -->
- * @binding-set MoveCursor3
- * {
- * bind "<Control>Right" { };
- * bind "<Control>Left" { };
- * }
- *
- * entry
- * {
- * -gtk-key-bindings: MoveCursor3;
- * }
- * ]|
- *
- * The above example will not have the desired effect of causing
- * “<Control>Right” and “<Control>Left” key presses to be ignored by GTK+.
- * Instead, it just causes any existing bindings from the bindings set
- * “MoveCursor3” to be deleted, so when “<Control>Right” or
- * “<Control>Left” are pressed, no binding for these keys is found in
- * binding set “MoveCursor3”. GTK+ will thus continue to search for
- * matching key bindings, and will eventually lookup and find the default
- * GTK+ bindings for entries which implement word movement. To keep GTK+
- * from activating its default bindings, the “unbind” keyword can be used
- * like this:
- *
- * |[ <!-- language="CSS" -->
- * @binding-set MoveCursor3
- * {
- * unbind "<Control>Right";
- * unbind "<Control>Left";
- * }
- *
- * entry
- * {
- * -gtk-key-bindings: MoveCursor3;
- * }
- * ]|
- *
- * Now, GTK+ will find a match when looking up “<Control>Right” and
- * “<Control>Left” key presses before it resorts to its default bindings,
- * and the match instructs it to abort (“unbind”) the search, so the key
- * presses are not consumed by this widget. As usual, further processing
- * of the key presses, e.g. by an entry’s parent widget, is now possible.
*/
/* --- defines --- */
projects / gtk4.git / commitdiff